Clarify what the @event is used for when calling gtk_drag_begin()

Signed-off-by: Federico Mena Quintero <federico@novell.com>

diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index 52d8edaa64ea826dbbec314fabe9f7f3a32bca0a..dc9a938309cb497418d9866958615c0aa26560f5 100644 (file)
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -2559,6 +2559,29 @@ gtk_drag_begin_internal (GtkWidget         *widget,
  * only needs to be used when the application is
  * starting drags itself, and is not needed when
  * gtk_drag_source_set() is used.
+ *
+ * The @event is used to retrieve the timestamp that will be used internally to
+ * grab the pointer.  If @event is #NULL, then GDK_CURRENT_TIME will be used.
+ * However, you should try to pass a real event in all cases, since that can be
+ * used by GTK+ to get information about the start position of the drag, for
+ * example if the @event is a GDK_MOTION_NOTIFY.
+ *
+ * Generally there are three cases when you want to start a drag by hand by calling
+ * this function:
+ *
+ * 1. During a button-press-event handler, if you want to start a drag immediately
+ * when the user presses the mouse button.  Pass the @event that you have in your
+ * button-press-event handler.
+ *
+ * 2. During a motion-notify-event handler, if you want to start a drag when the mouse
+ * moves past a certain threshold distance after a button-press.  Pass the @event that you
+ * have in your motion-notify-event handler.
+ *
+ * 3. During a timeout handler, if you want to start a drag after the mouse
+ * button is held down for some time.  Try to save the last event that you got
+ * from the mouse, using gdk_event_copy(), and pass it to this function
+ * (remember to free the event with gdk_event_free() when you are done).  If you
+ * can really not pass a real event, pass #NULL instead.
  * 
  * Return value: the context for this drag.
  **/